/**
 * @file file_transfer.c
 * @brief 文件传输数据模块实现
 * @details 本文件实现了104协议的文件传输数据处理功能，包括文件属性、
 *          文件传输命令、文件传输响应等数据类型的序列化和反序列化操作。
 *          支持完整的数据转换和验证功能。
 * 
 * @author zyb
 * @date 2025-10-17
 * @version 1.0
 * 
 * @note 所有函数都遵循104协议规范，确保严格的数据处理
 * @warning 数据转换失败时应返回相应的错误码，便于上层处理
 * 
 * @see file_transfer.h
 * @see protocol_types.h
 * @see buffer_utils.h
 * @see time_utils.h
 */

#include "../include/file_transfer.h"
#include "../../common/types/include/protocol_types.h"
#include "../../../../../common/utils/include/buffer_utils.h"
#include "../../common/utils/include/time_utils.h"
#include "../../common/error/include/error_codes.h"
#include "../../common/utils/include/validation_utils.h"
#include "../../../../../common/logs/include/logger.h"
#include <string.h>
#include <stdlib.h>

// 定义模块名称
#define LOG_MODULE_NAME "FILE_TRANSFER"

/* ==================== 文件属性处理函数实现 ==================== */

/**
 * @brief 文件属性转换为字节数组
 * @details 将文件属性结构转换为104协议规定的字节数组格式。
 *          按照协议规范进行数据序列化。
 * 
 * @param file_attr 文件属性结构，不能为NULL
 * @param buffer 输出缓冲区，不能为NULL
 * @param buffer_size 缓冲区大小
 * @param actual_length 实际写入长度输出，不能为NULL
 * @return 协议错误码
 *         - PROTOCOL_SUCCESS: 转换成功
 *         - PROTOCOL_ERROR_NULL_POINTER: 空指针错误
 *         - PROTOCOL_ERROR_BUFFER_TOO_SMALL: 缓冲区太小
 *         - PROTOCOL_ERROR_DATA_INVALID_VALUE: 数据值无效
 * 
 * @note 按照104协议规范进行数据序列化
 * @warning 缓冲区大小必须足够容纳转换后的数据
 * 
 * @see bytes_to_file_attributes
 * @see validate_file_attributes
 * @see buffer_write_u32
 * @see buffer_write_string
 */
protocol_error_t file_attributes_to_bytes(const file_attributes_t* file_attr,
                                        u8* buffer, u32 buffer_size, u32* actual_length) {
    LOG_DEBUG(LOG_MODULE_NAME, "转换文件属性到字节数组: file_attr=%p, buffer=%p, buffer_size=%u", 
              file_attr, buffer, buffer_size);
    
    if (file_attr == NULL || buffer == NULL || actual_length == NULL) {
        LOG_ERROR(LOG_MODULE_NAME, "空指针参数错误");
        return PROTOCOL_ERROR_NULL_POINTER;
    }
    
    /* 验证文件属性 */
    LOG_DEBUG(LOG_MODULE_NAME, "验证文件属性");
    if (!is_file_attributes_valid(file_attr)) {
        LOG_ERROR(LOG_MODULE_NAME, "无效的文件属性");
        return PROTOCOL_ERROR_DATA_INVALID_VALUE;
    }
    LOG_DEBUG(LOG_MODULE_NAME, "文件属性验证通过");
    
    /* 检查缓冲区大小 */
    u32 required_size = 1 + 4 + 7; /* 文件属性(1字节) + 文件大小(4字节) + 文件时间(7字节) */
    if (buffer_size < required_size) {
        LOG_ERROR(LOG_MODULE_NAME, "缓冲区太小: %u < %u", buffer_size, required_size);
        return PROTOCOL_ERROR_BUFFER_TOO_SMALL;
    }
    LOG_DEBUG(LOG_MODULE_NAME, "缓冲区大小检查通过: %u >= %u", buffer_size, required_size);
    
    u32 offset = 0;
    
    /* 写入文件属性 */
    LOG_DEBUG(LOG_MODULE_NAME, "写入文件属性: 0x%02X, 偏移: %u", file_attr->attributes, offset);
    buffer[offset] = file_attr->attributes;
    offset += 1;
    
    /* 写入文件大小 */
    LOG_DEBUG(LOG_MODULE_NAME, "写入文件大小: %u, 偏移: %u", file_attr->file_size, offset);
    buffer_write_u32(&buffer[offset], 0, file_attr->file_size, 0);
    offset += 4;
    
    /* 写入文件时间 */
    LOG_DEBUG(LOG_MODULE_NAME, "写入文件时间, 偏移: %u", offset);
    memcpy(&buffer[offset], &file_attr->file_time, 7);
    offset += 7;
    
    *actual_length = offset;
    LOG_INFO(LOG_MODULE_NAME, "文件属性成功转换为字节数组，实际长度: %u", *actual_length);
    return PROTOCOL_SUCCESS;
}

/**
 * @brief 字节数组转换为文件属性
 * @details 将104协议规定的字节数组格式转换为文件属性结构。
 *          按照协议规范进行数据反序列化。
 * 
 * @param data 字节数组，不能为NULL
 * @param length 数据长度
 * @param file_attr 文件属性结构输出，不能为NULL
 * @return 协议错误码
 *         - PROTOCOL_SUCCESS: 转换成功
 *         - PROTOCOL_ERROR_NULL_POINTER: 空指针错误
 *         - PROTOCOL_ERROR_BUFFER_TOO_SMALL: 数据长度不足
 *         - PROTOCOL_ERROR_DATA_INVALID_VALUE: 数据值无效
 * 
 * @note 按照104协议规范进行数据反序列化
 * @warning 数据长度必须足够容纳文件属性
 * 
 * @see file_attributes_to_bytes
 * @see validate_file_attributes
 * @see buffer_read_u32
 */
protocol_error_t bytes_to_file_attributes(const u8* data, u32 length,
                                         file_attributes_t* file_attr) {
    LOG_DEBUG(LOG_MODULE_NAME, "转换字节数组到文件属性: data=%p, length=%u, file_attr=%p", 
              data, length, file_attr);
    
    if (data == NULL || file_attr == NULL) {
        LOG_ERROR(LOG_MODULE_NAME, "空指针参数错误");
        return PROTOCOL_ERROR_NULL_POINTER;
    }
    
    /* 检查数据长度 */
    u32 required_size = 1 + 4 + 7; /* 文件属性(1字节) + 文件大小(4字节) + 文件时间(7字节) */
    if (length < required_size) {
        LOG_ERROR(LOG_MODULE_NAME, "数据长度不足: %u < %u", length, required_size);
        return PROTOCOL_ERROR_BUFFER_TOO_SMALL;
    }
    LOG_DEBUG(LOG_MODULE_NAME, "数据长度检查通过: %u >= %u", length, required_size);
    
    u32 offset = 0;
    
    /* 读取文件属性 */
    file_attr->attributes = data[offset];
    offset += 1;
    LOG_DEBUG(LOG_MODULE_NAME, "读取文件属性: 0x%02X, 偏移: %u", file_attr->attributes, offset);
    
    /* 读取文件大小 */
    buffer_read_u32(&data[offset], 0, &file_attr->file_size, 0);
    offset += 4;
    LOG_DEBUG(LOG_MODULE_NAME, "读取文件大小: %u, 偏移: %u", file_attr->file_size, offset);
    
    /* 读取文件时间 */
    memcpy(&file_attr->file_time, &data[offset], 7);
    offset += 7;
    LOG_DEBUG(LOG_MODULE_NAME, "读取文件时间, 偏移: %u", offset);
    
    /* 验证转换后的数据 */
    if (!is_file_attributes_valid(file_attr)) {
        LOG_ERROR(LOG_MODULE_NAME, "转换后的文件属性无效");
        return PROTOCOL_ERROR_DATA_INVALID_VALUE;
    }
    
    LOG_INFO(LOG_MODULE_NAME, "字节数组成功转换为文件属性: attributes=0x%02X, file_size=%u", 
             file_attr->attributes, file_attr->file_size);
    return PROTOCOL_SUCCESS;
}

/**
 * @brief 验证文件属性
 * @details 验证文件属性结构的完整性和有效性。
 *          检查文件ID、文件长度、文件类型等的有效性。
 * 
 * @param file_attr 文件属性结构，不能为NULL
 * @return 验证结果
 *         - 1: 文件属性有效
 *         - 0: 文件属性无效
 * 
 * @note 验证文件ID、文件长度、文件类型等的有效性
 * @warning 输入指针不能为NULL
 * 
 * @see is_file_id_valid
 * @see is_file_length_valid
 * @see is_file_type_valid
 * @see file_attributes_t
 */
int validate_file_attributes(const file_attributes_t* file_attr) {
    if (file_attr == NULL) {
        return 0;
    }
    
    return (is_file_size_valid(file_attr->file_size));
}

/* ==================== 文件传输命令处理函数实现 ==================== */

/**
 * @brief 文件传输命令转换为字节数组
 * @details 将文件传输命令结构转换为104协议规定的字节数组格式。
 *          按照协议规范进行数据序列化。
 * 
 * @param command 文件传输命令结构，不能为NULL
 * @param buffer 输出缓冲区，不能为NULL
 * @param buffer_size 缓冲区大小
 * @param actual_length 实际写入长度输出，不能为NULL
 * @return 协议错误码
 *         - PROTOCOL_SUCCESS: 转换成功
 *         - PROTOCOL_ERROR_NULL_POINTER: 空指针错误
 *         - PROTOCOL_ERROR_BUFFER_TOO_SMALL: 缓冲区太小
 *         - PROTOCOL_ERROR_DATA_INVALID_VALUE: 数据值无效
 * 
 * @note 按照104协议规范进行数据序列化
 * @warning 缓冲区大小必须足够容纳转换后的数据
 * 
 * @see bytes_to_file_transfer_command
 * @see validate_file_transfer_command
 * @see buffer_write_u32
 * @see buffer_write_u8
 * @see buffer_write_string
 */
protocol_error_t file_transfer_command_to_bytes(const file_transfer_command_t* command,
                                              u8* buffer, u32 buffer_size, u32* actual_length) {
    LOG_DEBUG(LOG_MODULE_NAME, "转换文件传输命令到字节数组: command=%p, buffer=%p, buffer_size=%u", 
              command, buffer, buffer_size);
    
    if (command == NULL || buffer == NULL || actual_length == NULL) {
        LOG_ERROR(LOG_MODULE_NAME, "空指针参数错误");
        return PROTOCOL_ERROR_NULL_POINTER;
    }
    
    /* 验证文件传输命令 */
    if (!is_file_transfer_command_valid(command)) {
        LOG_ERROR(LOG_MODULE_NAME, "无效的文件传输命令");
        return PROTOCOL_ERROR_DATA_INVALID_VALUE;
    }
    LOG_DEBUG(LOG_MODULE_NAME, "文件传输命令验证通过");
    
    /* 检查缓冲区大小 */
    u32 required_size = 4 + 1 + 4 + 4 + 4; /* 文件ID(4字节) + 操作类型(1字节) + 偏移(4字节) + 长度(4字节) + 校验和(4字节) */
    if (buffer_size < required_size) {
        LOG_ERROR(LOG_MODULE_NAME, "缓冲区太小: %u < %u", buffer_size, required_size);
        return PROTOCOL_ERROR_BUFFER_TOO_SMALL;
    }
    LOG_DEBUG(LOG_MODULE_NAME, "缓冲区大小检查通过: %u >= %u", buffer_size, required_size);
    
    u32 offset = 0;
    
    /* 写入文件ID */
    buffer_write_u32(&buffer[offset], 0, command->file_id, 0);
    offset += 4;
    LOG_DEBUG(LOG_MODULE_NAME, "写入文件ID: %u, 偏移: %u", command->file_id, offset);
    
    /* 写入操作类型 */
    buffer[offset] = (u8)command->operation_type;
    offset += 1;
    LOG_DEBUG(LOG_MODULE_NAME, "写入操作类型: %u, 偏移: %u", command->operation_type, offset);
    
    /* 写入偏移 */
    buffer_write_u32(&buffer[offset], 0, command->offset, 0);
    offset += 4;
    LOG_DEBUG(LOG_MODULE_NAME, "写入偏移: %u, 偏移: %u", command->offset, offset);
    
    /* 写入长度 */
    buffer_write_u32(&buffer[offset], 0, command->length, 0);
    offset += 4;
    LOG_DEBUG(LOG_MODULE_NAME, "写入长度: %u, 偏移: %u", command->length, offset);
    
    /* 写入校验和 */
    buffer_write_u32(&buffer[offset], 0, command->checksum, 0);
    offset += 4;
    LOG_DEBUG(LOG_MODULE_NAME, "写入校验和: %u, 偏移: %u", command->checksum, offset);
    
    *actual_length = offset;
    LOG_INFO(LOG_MODULE_NAME, "文件传输命令成功转换为字节数组: file_id=%u, operation_type=%u, actual_length=%u", 
             command->file_id, command->operation_type, *actual_length);
    return PROTOCOL_SUCCESS;
}

/**
 * @brief 字节数组转换为文件传输命令
 * @details 将104协议规定的字节数组格式转换为文件传输命令结构。
 *          按照协议规范进行数据反序列化。
 * 
 * @param data 字节数组，不能为NULL
 * @param length 数据长度
 * @param command 文件传输命令结构输出，不能为NULL
 * @return 协议错误码
 *         - PROTOCOL_SUCCESS: 转换成功
 *         - PROTOCOL_ERROR_NULL_POINTER: 空指针错误
 *         - PROTOCOL_ERROR_BUFFER_TOO_SMALL: 数据长度不足
 *         - PROTOCOL_ERROR_DATA_INVALID_VALUE: 数据值无效
 * 
 * @note 按照104协议规范进行数据反序列化
 * @warning 数据长度必须足够容纳文件传输命令
 * 
 * @see file_transfer_command_to_bytes
 * @see validate_file_transfer_command
 * @see buffer_read_u32
 * @see buffer_read_u8
 */
protocol_error_t bytes_to_file_transfer_command(const u8* data, u32 length,
                                               file_transfer_command_t* command) {
    LOG_DEBUG(LOG_MODULE_NAME, "转换字节数组到文件传输命令: data=%p, length=%u, command=%p", 
              data, length, command);
    
    if (data == NULL || command == NULL) {
        LOG_ERROR(LOG_MODULE_NAME, "空指针参数错误");
        return PROTOCOL_ERROR_NULL_POINTER;
    }
    
    /* 检查数据长度 */
    u32 required_size = 4 + 1 + 4 + 4 + 4; /* 文件ID(4字节) + 操作类型(1字节) + 偏移(4字节) + 长度(4字节) + 校验和(4字节) */
    if (length < required_size) {
        LOG_ERROR(LOG_MODULE_NAME, "数据长度不足: %u < %u", length, required_size);
        return PROTOCOL_ERROR_BUFFER_TOO_SMALL;
    }
    LOG_DEBUG(LOG_MODULE_NAME, "数据长度检查通过: %u >= %u", length, required_size);
    
    u32 offset = 0;
    
    /* 读取文件ID */
    buffer_read_u32(&data[offset], 0, &command->file_id, 0);
    offset += 4;
    LOG_DEBUG(LOG_MODULE_NAME, "读取文件ID: %u, 偏移: %u", command->file_id, offset);
    
    /* 读取操作类型 */
    command->operation_type = (file_operation_type_t)data[offset];
    offset += 1;
    LOG_DEBUG(LOG_MODULE_NAME, "读取操作类型: %u, 偏移: %u", command->operation_type, offset);
    
    /* 读取偏移 */
    buffer_read_u32(&data[offset], 0, &command->offset, 0);
    offset += 4;
    LOG_DEBUG(LOG_MODULE_NAME, "读取偏移: %u, 偏移: %u", command->offset, offset);
    
    /* 读取长度 */
    buffer_read_u32(&data[offset], 0, &command->length, 0);
    offset += 4;
    LOG_DEBUG(LOG_MODULE_NAME, "读取长度: %u, 偏移: %u", command->length, offset);
    
    /* 读取校验和 */
    buffer_read_u32(&data[offset], 0, &command->checksum, 0);
    offset += 4;
    LOG_DEBUG(LOG_MODULE_NAME, "读取校验和: %u, 偏移: %u", command->checksum, offset);
    
    /* 验证转换后的数据 */
    if (!is_file_transfer_command_valid(command)) {
        LOG_ERROR(LOG_MODULE_NAME, "转换后的文件传输命令无效");
        return PROTOCOL_ERROR_DATA_INVALID_VALUE;
    }
    
    LOG_INFO(LOG_MODULE_NAME, "字节数组成功转换为文件传输命令: file_id=%u, operation_type=%u, offset=%u, length=%u", 
             command->file_id, command->operation_type, command->offset, command->length);
    return PROTOCOL_SUCCESS;
}

/**
 * @brief 验证文件传输命令
 * @details 验证文件传输命令结构的完整性和有效性。
 *          检查文件ID、操作类型、偏移、长度等的有效性。
 * 
 * @param command 文件传输命令结构，不能为NULL
 * @return 验证结果
 *         - 1: 文件传输命令有效
 *         - 0: 文件传输命令无效
 * 
 * @note 验证文件ID、操作类型、偏移、长度等的有效性
 * @warning 输入指针不能为NULL
 * 
 * @see is_file_id_valid
 * @see is_file_operation_type_valid
 * @see is_file_offset_valid
 * @see is_file_length_valid
 * @see file_transfer_command_t
 */
int validate_file_transfer_command(const file_transfer_command_t* command) {
    if (command == NULL) {
        return 0;
    }
    
    return (is_file_id_valid(command->file_id) && 
            is_file_operation_type_valid(command->operation_type) && 
            is_file_offset_valid(command->offset) && 
            is_file_length_valid(command->length));
}

/* ==================== 文件传输响应处理函数实现 ==================== */

/**
 * @brief 文件传输响应转换为字节数组
 * @details 将文件传输响应结构转换为104协议规定的字节数组格式。
 *          按照协议规范进行数据序列化。
 * 
 * @param response 文件传输响应结构，不能为NULL
 * @param buffer 输出缓冲区，不能为NULL
 * @param buffer_size 缓冲区大小
 * @param actual_length 实际写入长度输出，不能为NULL
 * @return 协议错误码
 *         - PROTOCOL_SUCCESS: 转换成功
 *         - PROTOCOL_ERROR_NULL_POINTER: 空指针错误
 *         - PROTOCOL_ERROR_BUFFER_TOO_SMALL: 缓冲区太小
 *         - PROTOCOL_ERROR_DATA_INVALID_VALUE: 数据值无效
 * 
 * @note 按照104协议规范进行数据序列化
 * @warning 缓冲区大小必须足够容纳转换后的数据
 * 
 * @see bytes_to_file_transfer_response
 * @see validate_file_transfer_response
 * @see buffer_write_u32
 * @see buffer_write_u8
 * @see buffer_write_u16
 */
protocol_error_t file_transfer_response_to_bytes(const file_transfer_response_t* response,
                                                u8* buffer, u32 buffer_size, u32* actual_length) {
    LOG_DEBUG(LOG_MODULE_NAME, "转换文件传输响应到字节数组: response=%p, buffer=%p, buffer_size=%u", 
              response, buffer, buffer_size);
    
    if (response == NULL || buffer == NULL || actual_length == NULL) {
        LOG_ERROR(LOG_MODULE_NAME, "空指针参数错误");
        return PROTOCOL_ERROR_NULL_POINTER;
    }
    
    /* 验证文件传输响应 */
    if (!is_file_transfer_response_valid(response)) {
        LOG_ERROR(LOG_MODULE_NAME, "无效的文件传输响应");
        return PROTOCOL_ERROR_DATA_INVALID_VALUE;
    }
    LOG_DEBUG(LOG_MODULE_NAME, "文件传输响应验证通过");
    
    /* 检查缓冲区大小 */
    u32 required_size = 4 + 1 + 2 + 4; /* 文件ID(4字节) + 状态(1字节) + 错误码(2字节) + 数据长度(4字节) */
    if (buffer_size < required_size) {
        LOG_ERROR(LOG_MODULE_NAME, "缓冲区太小: %u < %u", buffer_size, required_size);
        return PROTOCOL_ERROR_BUFFER_TOO_SMALL;
    }
    LOG_DEBUG(LOG_MODULE_NAME, "缓冲区大小检查通过: %u >= %u", buffer_size, required_size);
    
    u32 offset = 0;
    
    /* 写入文件ID */
    buffer_write_u32(&buffer[offset], 0, response->file_id, 0);
    offset += 4;
    LOG_DEBUG(LOG_MODULE_NAME, "写入文件ID: %u, 偏移: %u", response->file_id, offset);
    
    /* 写入操作类型 */
    buffer[offset] = (u8)response->operation_type;
    offset += 1;
    LOG_DEBUG(LOG_MODULE_NAME, "写入操作类型: %u, 偏移: %u", response->operation_type, offset);
    
    /* 写入错误码 */
    buffer_write_u16(&buffer[offset], 0, response->error_code, 0);
    offset += 2;
    LOG_DEBUG(LOG_MODULE_NAME, "写入错误码: %u, 偏移: %u", response->error_code, offset);
    
    /* 写入数据长度 */
    buffer_write_u32(&buffer[offset], 0, response->data_length, 0);
    offset += 4;
    LOG_DEBUG(LOG_MODULE_NAME, "写入数据长度: %u, 偏移: %u", response->data_length, offset);
    
    *actual_length = offset;
    LOG_INFO(LOG_MODULE_NAME, "文件传输响应成功转换为字节数组: file_id=%u, operation_type=%u, error_code=%u, actual_length=%u", 
             response->file_id, response->operation_type, response->error_code, *actual_length);
    return PROTOCOL_SUCCESS;
}

/**
 * @brief 字节数组转换为文件传输响应
 * @details 将104协议规定的字节数组格式转换为文件传输响应结构。
 *          按照协议规范进行数据反序列化。
 * 
 * @param data 字节数组，不能为NULL
 * @param length 数据长度
 * @param response 文件传输响应结构输出，不能为NULL
 * @return 协议错误码
 *         - PROTOCOL_SUCCESS: 转换成功
 *         - PROTOCOL_ERROR_NULL_POINTER: 空指针错误
 *         - PROTOCOL_ERROR_BUFFER_TOO_SMALL: 数据长度不足
 *         - PROTOCOL_ERROR_DATA_INVALID_VALUE: 数据值无效
 * 
 * @note 按照104协议规范进行数据反序列化
 * @warning 数据长度必须足够容纳文件传输响应
 * 
 * @see file_transfer_response_to_bytes
 * @see validate_file_transfer_response
 * @see buffer_read_u32
 * @see buffer_read_u8
 * @see buffer_read_u16
 */
protocol_error_t bytes_to_file_transfer_response(const u8* data, u32 length,
                                                file_transfer_response_t* response) {
    LOG_DEBUG(LOG_MODULE_NAME, "转换字节数组到文件传输响应: data=%p, length=%u, response=%p", 
              data, length, response);
    
    if (data == NULL || response == NULL) {
        LOG_ERROR(LOG_MODULE_NAME, "空指针参数错误");
        return PROTOCOL_ERROR_NULL_POINTER;
    }
    
    /* 检查数据长度 */
    u32 required_size = 4 + 1 + 2 + 4; /* 文件ID(4字节) + 状态(1字节) + 错误码(2字节) + 数据长度(4字节) */
    if (length < required_size) {
        LOG_ERROR(LOG_MODULE_NAME, "数据长度不足: %u < %u", length, required_size);
        return PROTOCOL_ERROR_BUFFER_TOO_SMALL;
    }
    LOG_DEBUG(LOG_MODULE_NAME, "数据长度检查通过: %u >= %u", length, required_size);
    
    u32 offset = 0;
    
    /* 读取文件ID */
    buffer_read_u32(&data[offset], 0, &response->file_id, 0);
    offset += 4;
    LOG_DEBUG(LOG_MODULE_NAME, "读取文件ID: %u, 偏移: %u", response->file_id, offset);
    
    /* 读取操作类型 */
    response->operation_type = (file_operation_type_t)data[offset];
    offset += 1;
    LOG_DEBUG(LOG_MODULE_NAME, "读取操作类型: %u, 偏移: %u", response->operation_type, offset);
    
    /* 读取错误码 */
    buffer_read_u16(&data[offset], 0, &response->error_code, 0);
    offset += 2;
    LOG_DEBUG(LOG_MODULE_NAME, "读取错误码: %u, 偏移: %u", response->error_code, offset);
    
    /* 读取数据长度 */
    buffer_read_u32(&data[offset], 0, &response->data_length, 0);
    offset += 4;
    LOG_DEBUG(LOG_MODULE_NAME, "读取数据长度: %u, 偏移: %u", response->data_length, offset);
    
    /* 验证转换后的数据 */
    if (!is_file_transfer_response_valid(response)) {
        LOG_ERROR(LOG_MODULE_NAME, "转换后的文件传输响应无效");
        return PROTOCOL_ERROR_DATA_INVALID_VALUE;
    }
    
    LOG_INFO(LOG_MODULE_NAME, "字节数组成功转换为文件传输响应: file_id=%u, operation_type=%u, error_code=%u, data_length=%u", 
             response->file_id, response->operation_type, response->error_code, response->data_length);
    return PROTOCOL_SUCCESS;
}

/**
 * @brief 验证文件传输响应
 * @details 验证文件传输响应结构的完整性和有效性。
 *          检查文件ID、状态、错误码、数据长度等的有效性。
 * 
 * @param response 文件传输响应结构，不能为NULL
 * @return 验证结果
 *         - 1: 文件传输响应有效
 *         - 0: 文件传输响应无效
 * 
 * @note 验证文件ID、状态、错误码、数据长度等的有效性
 * @warning 输入指针不能为NULL
 * 
 * @see is_file_id_valid
 * @see is_file_status_valid
 * @see is_file_error_code_valid
 * @see is_file_data_length_valid
 * @see file_transfer_response_t
 */
int validate_file_transfer_response(const file_transfer_response_t* response) {
    if (response == NULL) {
        return 0;
    }
    
    return (is_file_id_valid(response->file_id) && 
            is_file_error_code_valid(response->error_code));
}

/* ==================== 辅助函数实现 ==================== */

/**
 * @brief 获取文件属性大小
 * @details 获取文件属性结构在字节数组中的大小。
 *          用于缓冲区大小计算。
 * 
 * @return 文件属性大小（字节）
 * 
 * @note 文件属性大小：24字节（文件ID4字节 + 文件长度4字节 + 文件日期4字节 + 文件时间4字节 + 文件类型4字节 + 文件权限4字节）
 * @warning 此函数是线程安全的
 * 
 * @see get_file_transfer_command_size
 * @see get_file_transfer_response_size
 * @see file_attributes_t
 */
u32 get_file_attributes_size(void) {
    LOG_DEBUG(LOG_MODULE_NAME, "获取文件属性大小");
    u32 size = 12; /* 文件属性(1字节) + 文件大小(4字节) + 文件时间(7字节) */
    LOG_INFO(LOG_MODULE_NAME, "文件属性大小: %u 字节", size);
    return size;
}

/**
 * @brief 获取文件传输命令大小
 * @details 获取文件传输命令结构在字节数组中的大小。
 *          用于缓冲区大小计算。
 * 
 * @return 文件传输命令大小（字节）
 * 
 * @note 文件传输命令大小：17字节（文件ID4字节 + 操作类型1字节 + 偏移4字节 + 长度4字节 + 校验和4字节）
 * @warning 此函数是线程安全的
 * 
 * @see get_file_attributes_size
 * @see get_file_transfer_response_size
 * @see file_transfer_command_t
 */
u32 get_file_transfer_command_size(void) {
    LOG_DEBUG(LOG_MODULE_NAME, "获取文件传输命令大小");
    u32 size = 17; /* 文件ID(4字节) + 操作类型(1字节) + 偏移(4字节) + 长度(4字节) + 校验和(4字节) */
    LOG_INFO(LOG_MODULE_NAME, "文件传输命令大小: %u 字节", size);
    return size;
}

/**
 * @brief 获取文件传输响应大小
 * @details 获取文件传输响应结构在字节数组中的大小。
 *          用于缓冲区大小计算。
 * 
 * @return 文件传输响应大小（字节）
 * 
 * @note 文件传输响应大小：11字节（文件ID4字节 + 状态1字节 + 错误码2字节 + 数据长度4字节）
 * @warning 此函数是线程安全的
 * 
 * @see get_file_attributes_size
 * @see get_file_transfer_command_size
 * @see file_transfer_response_t
 */
u32 get_file_transfer_response_size(void) {
    LOG_DEBUG(LOG_MODULE_NAME, "获取文件传输响应大小");
    u32 size = 11; /* 文件ID(4字节) + 状态(1字节) + 错误码(2字节) + 数据长度(4字节) */
    LOG_INFO(LOG_MODULE_NAME, "文件传输响应大小: %u 字节", size);
    return size;
}

/* ==================== 文件操作类型处理函数实现 ==================== */

/**
 * @brief 获取文件操作类型名称
 * @details 根据文件操作类型枚举值获取对应的中文名称。
 *          用于调试和日志输出。
 * 
 * @param type 文件操作类型枚举值
 * @return 文件操作类型名称字符串
 * 
 * @note 返回的字符串是静态的，不需要释放
 * @warning 无效类型返回"未知类型"
 * 
 * @see file_operation_type_t
 * @see get_file_operation_type_description
 */
const char* get_file_operation_type_name(file_operation_type_t type) {
    LOG_DEBUG(LOG_MODULE_NAME, "获取文件操作类型名称: type=%u", type);
    const char* name;
    
    switch (type) {
        case FILE_OP_READ_DIRECTORY:
            name = "读目录";
            break;
        case FILE_OP_READ_DIRECTORY_CONFIRM:
            name = "读目录确认";
            break;
        case FILE_OP_READ_FILE_ACTIVATE:
            name = "读文件激活";
            break;
        case FILE_OP_READ_FILE_ACTIVATE_CONFIRM:
            name = "读文件激活确认";
            break;
        case FILE_OP_READ_FILE_DATA:
            name = "读文件数据传输";
            break;
        case FILE_OP_READ_FILE_DATA_CONFIRM:
            name = "读文件数据传输确认";
            break;
        case FILE_OP_WRITE_FILE_ACTIVATE:
            name = "写文件激活";
            break;
        case FILE_OP_WRITE_FILE_ACTIVATE_CONFIRM:
            name = "写文件激活确认";
            break;
        case FILE_OP_WRITE_FILE_DATA:
            name = "写文件数据传输";
            break;
        case FILE_OP_WRITE_FILE_DATA_CONFIRM:
            name = "写文件数据传输确认";
            break;
        default:
            name = "未知类型";
            break;
    }
    
    LOG_INFO(LOG_MODULE_NAME, "文件操作类型名称: %s", name);
    return name;
}

/**
 * @brief 获取文件操作类型描述
 * @details 根据文件操作类型枚举值获取对应的详细描述。
 *          用于调试和日志输出。
 * 
 * @param type 文件操作类型枚举值
 * @return 文件操作类型描述字符串
 * 
 * @note 返回的字符串是静态的，不需要释放
 * @warning 无效类型返回"未知类型"
 * 
 * @see file_operation_type_t
 * @see get_file_operation_type_name
 */
const char* get_file_operation_type_description(file_operation_type_t type) {
    LOG_DEBUG(LOG_MODULE_NAME, "获取文件操作类型描述: type=%u", type);
    const char* description;
    
    switch (type) {
        case FILE_OP_READ_DIRECTORY:
            description = "读目录操作，用于读取目录内容";
            break;
        case FILE_OP_READ_DIRECTORY_CONFIRM:
            description = "读目录确认操作，用于确认目录读取";
            break;
        case FILE_OP_READ_FILE_ACTIVATE:
            description = "读文件激活操作，用于激活文件读取";
            break;
        case FILE_OP_READ_FILE_ACTIVATE_CONFIRM:
            description = "读文件激活确认操作，用于确认文件读取激活";
            break;
        case FILE_OP_READ_FILE_DATA:
            description = "读文件数据传输操作，用于传输文件数据";
            break;
        case FILE_OP_READ_FILE_DATA_CONFIRM:
            description = "读文件数据传输确认操作，用于确认文件数据传输";
            break;
        case FILE_OP_WRITE_FILE_ACTIVATE:
            description = "写文件激活操作，用于激活文件写入";
            break;
        case FILE_OP_WRITE_FILE_ACTIVATE_CONFIRM:
            description = "写文件激活确认操作，用于确认文件写入激活";
            break;
        case FILE_OP_WRITE_FILE_DATA:
            description = "写文件数据传输操作，用于传输文件数据";
            break;
        case FILE_OP_WRITE_FILE_DATA_CONFIRM:
            description = "写文件数据传输确认操作，用于确认文件数据传输";
            break;
        default:
            description = "未知类型";
            break;
    }
    
    LOG_INFO(LOG_MODULE_NAME, "文件操作类型描述: %s", description);
    return description;
}

/* ==================== 文件状态处理函数实现 ==================== */

/**
 * @brief 获取文件状态名称
 * @details 根据文件状态枚举值获取对应的中文名称。
 *          用于调试和日志输出。
 * 
 * @param status 文件状态枚举值
 * @return 文件状态名称字符串
 * 
 * @note 返回的字符串是静态的，不需要释放
 * @warning 无效状态返回"未知状态"
 * 
 * @see file_status_t
 * @see get_file_status_description
 */
const char* get_file_status_name(file_status_t status) {
    LOG_DEBUG(LOG_MODULE_NAME, "获取文件状态名称: status=%u", status);
    const char* name;
    
    switch (status) {
        case FILE_STATUS_SUCCESS:
            name = "成功";
            break;
        case FILE_STATUS_FAILURE:
            name = "失败";
            break;
        case FILE_STATUS_UNKNOWN_ERROR:
            name = "未知错误";
            break;
        case FILE_STATUS_FILENAME_NOT_SUPPORTED:
            name = "文件名不支持";
            break;
        case FILE_STATUS_LENGTH_OUT_OF_RANGE:
            name = "长度超范围";
            break;
        case FILE_STATUS_CHECKSUM_ERROR:
            name = "校验和错误";
            break;
        case FILE_STATUS_FILE_LENGTH_MISMATCH:
            name = "文件长度不对应";
            break;
        case FILE_STATUS_FILE_ID_MISMATCH:
            name = "文件ID与激活ID不一致";
            break;
        default:
            name = "未知状态";
            break;
    }
    
    LOG_INFO(LOG_MODULE_NAME, "文件状态名称: %s", name);
    return name;
}

/**
 * @brief 获取文件状态描述
 * @details 根据文件状态枚举值获取对应的详细描述。
 *          用于调试和日志输出。
 * 
 * @param status 文件状态枚举值
 * @return 文件状态描述字符串
 * 
 * @note 返回的字符串是静态的，不需要释放
 * @warning 无效状态返回"未知状态"
 * 
 * @see file_status_t
 * @see get_file_status_name
 */
const char* get_file_status_description(file_status_t status) {
    LOG_DEBUG(LOG_MODULE_NAME, "获取文件状态描述: status=%u", status);
    const char* description;
    
    switch (status) {
        case FILE_STATUS_SUCCESS:
            description = "文件操作成功完成";
            break;
        case FILE_STATUS_FAILURE:
            description = "文件操作失败";
            break;
        case FILE_STATUS_UNKNOWN_ERROR:
            description = "发生未知错误";
            break;
        case FILE_STATUS_FILENAME_NOT_SUPPORTED:
            description = "文件名格式不支持";
            break;
        case FILE_STATUS_LENGTH_OUT_OF_RANGE:
            description = "文件长度超出允许范围";
            break;
        case FILE_STATUS_CHECKSUM_ERROR:
            description = "文件校验和错误";
            break;
        case FILE_STATUS_FILE_LENGTH_MISMATCH:
            description = "文件长度与预期不符";
            break;
        case FILE_STATUS_FILE_ID_MISMATCH:
            description = "文件ID与激活ID不一致";
            break;
        default:
            description = "未知状态";
            break;
    }
    
    LOG_INFO(LOG_MODULE_NAME, "文件状态描述: %s", description);
    return description;
}

/* ==================== 文件传输验证函数实现 ==================== */

/**
 * @brief 验证文件ID
 * @details 验证文件ID是否在有效范围内。
 *          文件ID范围：1-4294967295
 * 
 * @param file_id 文件ID
 * @return 验证结果
 *         - 1: 文件ID有效
 *         - 0: 文件ID无效
 * 
 * @note 文件ID范围：1-4294967295
 * @warning 文件ID不能为0
 * 
 * @see is_file_length_valid
 * @see is_file_type_valid
 */
int is_file_id_valid(u32 file_id) {
    LOG_DEBUG(LOG_MODULE_NAME, "验证文件ID: %u", file_id);
    int valid = (file_id > 0 && file_id <= 4294967295U);
    LOG_INFO(LOG_MODULE_NAME, "文件ID验证结果: %s", valid ? "有效" : "无效");
    return valid;
}

/**
 * @brief 验证文件长度
 * @details 验证文件长度是否在有效范围内。
 *          文件长度范围：0-4294967295
 * 
 * @param file_length 文件长度
 * @return 验证结果
 *         - 1: 文件长度有效
 *         - 0: 文件长度无效
 * 
 * @note 文件长度范围：0-4294967295
 * @warning 文件长度不能为负数
 * 
 * @see is_file_id_valid
 * @see is_file_type_valid
 */
int is_file_length_valid(u32 file_length) {
    LOG_DEBUG(LOG_MODULE_NAME, "验证文件长度: %u", file_length);
    int valid = (file_length <= 4294967295U);
    LOG_INFO(LOG_MODULE_NAME, "文件长度验证结果: %s", valid ? "有效" : "无效");
    return valid;
}

/**
 * @brief 验证文件类型
 * @details 验证文件类型是否在有效范围内。
 *          文件类型范围：0-4294967295
 * 
 * @param file_type 文件类型
 * @return 验证结果
 *         - 1: 文件类型有效
 *         - 0: 文件类型无效
 * 
 * @note 文件类型范围：0-4294967295
 * @warning 文件类型不能为负数
 * 
 * @see is_file_id_valid
 * @see is_file_length_valid
 */
int is_file_type_valid(u32 file_type) {
    LOG_DEBUG(LOG_MODULE_NAME, "验证文件类型: %u", file_type);
    int valid = (file_type <= 4294967295U);
    LOG_INFO(LOG_MODULE_NAME, "文件类型验证结果: %s", valid ? "有效" : "无效");
    return valid;
}

/**
 * @brief 验证文件操作类型
 * @details 验证文件操作类型是否在有效范围内。
 *          文件操作类型范围：1-10
 * 
 * @param operation_type 文件操作类型
 * @return 验证结果
 *         - 1: 文件操作类型有效
 *         - 0: 文件操作类型无效
 * 
 * @note 文件操作类型范围：1-10
 * @warning 文件操作类型不能为0
 * 
 * @see is_file_status_valid
 * @see is_file_error_code_valid
 */
int is_file_operation_type_valid(file_operation_type_t operation_type) {
    LOG_DEBUG(LOG_MODULE_NAME, "验证文件操作类型: %u", operation_type);
    int valid = (operation_type >= FILE_OP_READ_DIRECTORY && 
                 operation_type <= FILE_OP_WRITE_FILE_DATA_CONFIRM);
    LOG_INFO(LOG_MODULE_NAME, "文件操作类型验证结果: %s", valid ? "有效" : "无效");
    return valid;
}

/**
 * @brief 验证文件偏移
 * @details 验证文件偏移是否在有效范围内。
 *          文件偏移范围：0-4294967295
 * 
 * @param offset 文件偏移
 * @return 验证结果
 *         - 1: 文件偏移有效
 *         - 0: 文件偏移无效
 * 
 * @note 文件偏移范围：0-4294967295
 * @warning 文件偏移不能为负数
 * 
 * @see is_file_length_valid
 * @see is_file_id_valid
 */
int is_file_offset_valid(u32 offset) {
    LOG_DEBUG(LOG_MODULE_NAME, "验证文件偏移: %u", offset);
    int valid = (offset <= 4294967295U);
    LOG_INFO(LOG_MODULE_NAME, "文件偏移验证结果: %s", valid ? "有效" : "无效");
    return valid;
}

/**
 * @brief 验证文件状态
 * @details 验证文件状态是否在有效范围内。
 *          文件状态范围：0-4
 * 
 * @param status 文件状态
 * @return 验证结果
 *         - 1: 文件状态有效
 *         - 0: 文件状态无效
 * 
 * @note 文件状态范围：0-4
 * @warning 文件状态不能为负数
 * 
 * @see is_file_operation_type_valid
 * @see is_file_error_code_valid
 */
int is_file_status_valid(file_status_t status) {
    LOG_DEBUG(LOG_MODULE_NAME, "验证文件状态: %u", status);
    int valid = (status >= FILE_STATUS_SUCCESS && 
                 status <= FILE_STATUS_FILE_ID_MISMATCH);
    LOG_INFO(LOG_MODULE_NAME, "文件状态验证结果: %s", valid ? "有效" : "无效");
    return valid;
}

/**
 * @brief 验证文件错误码
 * @details 验证文件错误码是否在有效范围内。
 *          文件错误码范围：0-65535
 * 
 * @param error_code 文件错误码
 * @return 验证结果
 *         - 1: 文件错误码有效
 *         - 0: 文件错误码无效
 * 
 * @note 文件错误码范围：0-65535
 * @warning 文件错误码不能为负数
 * 
 * @see is_file_status_valid
 * @see is_file_operation_type_valid
 */
int is_file_error_code_valid(u16 error_code) {
    LOG_DEBUG(LOG_MODULE_NAME, "验证文件错误码: %u", error_code);
    int valid = 1; // u16类型总是有效的
    LOG_INFO(LOG_MODULE_NAME, "文件错误码验证结果: %s", valid ? "有效" : "无效");
    return valid;
}

/**
 * @brief 验证文件数据长度
 * @details 验证文件数据长度是否在有效范围内。
 *          文件数据长度范围：0-4294967295
 * 
 * @param data_length 文件数据长度
 * @return 验证结果
 *         - 1: 文件数据长度有效
 *         - 0: 文件数据长度无效
 * 
 * @note 文件数据长度范围：0-4294967295
 * @warning 文件数据长度不能为负数
 * 
 * @see is_file_length_valid
 * @see is_file_offset_valid
 */
int is_file_data_length_valid(u32 data_length) {
    LOG_DEBUG(LOG_MODULE_NAME, "验证文件数据长度: %u", data_length);
    int valid = (data_length <= 4294967295U);
    LOG_INFO(LOG_MODULE_NAME, "文件数据长度验证结果: %s", valid ? "有效" : "无效");
    return valid;
}

/**
 * @brief 验证文件属性
 * @details 验证文件属性结构是否有效。
 *          检查文件大小是否在有效范围内。
 * 
 * @param file_attr 文件属性结构指针
 * @return 验证结果
 *         - 1: 文件属性有效
 *         - 0: 文件属性无效
 * 
 * @note 文件大小范围：0-4294967295
 * @warning 文件属性指针不能为NULL
 * 
 * @see file_attributes_t
 * @see is_file_size_valid
 */
int is_file_attributes_valid(const file_attributes_t* file_attr) {
    LOG_DEBUG(LOG_MODULE_NAME, "验证文件属性: file_attr=%p", file_attr);
    
    if (file_attr == NULL) {
        LOG_ERROR(LOG_MODULE_NAME, "文件属性指针为空");
        return 0;
    }
    
    /* 验证文件大小 */
    if (!is_file_size_valid(file_attr->file_size)) {
        LOG_ERROR(LOG_MODULE_NAME, "文件大小无效: %u", file_attr->file_size);
        return 0;
    }
    
    LOG_INFO(LOG_MODULE_NAME, "文件属性验证通过: attributes=0x%02X, file_size=%u", 
             file_attr->attributes, file_attr->file_size);
    return 1;
}

int is_file_size_valid(u32 file_size) {
    LOG_DEBUG(LOG_MODULE_NAME, "验证文件大小: %u", file_size);
    int valid = (file_size <= 4294967295U);
    LOG_INFO(LOG_MODULE_NAME, "文件大小验证结果: %s", valid ? "有效" : "无效");
    return valid;
}


int is_file_transfer_command_valid(const file_transfer_command_t* command) {
    LOG_DEBUG(LOG_MODULE_NAME, "验证文件传输命令: command=%p", command);
    
    if (command == NULL) {
        LOG_ERROR(LOG_MODULE_NAME, "文件传输命令指针为空");
        return 0;
    }
    
    int valid = (is_file_id_valid(command->file_id) && 
                 is_file_operation_type_valid(command->operation_type) && 
                 is_file_offset_valid(command->offset) && 
                 is_file_length_valid(command->length));
    
    LOG_INFO(LOG_MODULE_NAME, "文件传输命令验证结果: %s", valid ? "有效" : "无效");
    return valid;
}

int is_file_transfer_response_valid(const file_transfer_response_t* response) {
    LOG_DEBUG(LOG_MODULE_NAME, "验证文件传输响应: response=%p", response);
    
    if (response == NULL) {
        LOG_ERROR(LOG_MODULE_NAME, "文件传输响应指针为空");
        return 0;
    }
    
    int valid = (is_file_id_valid(response->file_id) && 
                 is_file_operation_type_valid(response->operation_type));
    
    LOG_INFO(LOG_MODULE_NAME, "文件传输响应验证结果: %s", valid ? "有效" : "无效");
    return valid;
}

